mudbox::Material Class Reference

#include <material.h>

Inheritance diagram for mudbox::Material:

Detailed Description

Describes a material of a geometry including its surface colors, transparency and texture information.

The material class is responsible for the appearance of a surface when its rendered. Each mesh in Mudbox has an associated material, and multiple meshes can use the same material instance.

When Mudbox renders the mesh, it first uses the associated material to prepare the opengl pipeline for the mesh by calling the Material::Activate() function. The material class is also used to determine the list of paintable textures over the surface. The functions Material::TextureCount() and Material::Texture() are used for this purpose. For more details, see the TexturePool class.

You can derive from the Material class to create your own custom materials with texture channels that control any parameters you wish. See the SDK examples.

How to access a specific texture value at a point on the surface:

1. Calculate the texture coordinate associated for the surface point. This can be done by calculating a linear conbination of the texture coordinates at the corners of the face based on the information you have about where the point is inside the face.

2. Decide which texture are you interested in, by examining the list of textures in the corrseponding material instance by calling the TextureCount() and Texture() functions. You can get the name of a texture by calling the Texture::Name() function. This list is dynamic is because it can changed depending on the material implementation. The default Mudbox material has a fixed list, but materials created from custom cgfx files can have very different texture lists.

3. Since Mudbox supports layers for each texture, you next need to choose the layer you are interested in. To do this, cast the pointer obtained in step 2 to LayerContainer. Once you have a pointer to a layercontainer instance, you can check the list of layers and their names. Finally you have to cast the layer to a TexturePool again.

4. Based on your interpolated texture coordinate, you have to select the proper tile in the TexturePool by calling TexturePool::Tile() function. (If the UV space of an object goes beyond the range 0-1, Mudbox uses multiple tiles to represent each layer of a texture.) Pass in a bounding box representing the tile you are interested in. For example, if the desired texture coordinate is 1.3, 3.4, then you would pass in a bounding box between ( 1, 3, 0 ) and ( 2, 4, 0 ). (In texture space, the third coordinate is always 0.) Once you get the tile, you would sample the texel at 0.3, 0.4 within that tile. (See next step)

5. Once you got the texture, copy it to an Image object by calling the Texture::CopyTo() function. You can easily access the color of the needed pixel by calling the Image::ColorAt() function. Note that copying a texture to an image is a slow process, so if you want to sample multiple surface points, it is smart to copy the textures only once, and cache it.


Public Types
enum	VertexDataUsage { eVDUPosition, eVDUNormal, eVDUTextureCoordinate, eVDUVertexColor, eVDUBoneIndices, eVDUBoneWeights, eVDUTangent, eVDUBinormal, eVDUDirectTextureCoordinate0, eVDUDirectTextureCoordinate1, eVDUDirectTextureCoordinate2, eVDUDirectTextureCoordinate3, eVDUDirectTextureCoordinate4, eVDUDirectTextureCoordinate5, eVDUDirectTextureCoordinate6, eVDUDirectTextureCoordinate7, eVDUNotUsed }
	This enum describes the usage of additional vertex data. More...
Public Member Functions
virtual const mudbox::ClassDesc *	RuntimeClass (void) const
	~Material ()
virtual bool	Activate (const Mesh *pMesh, const AxisAlignedBoundingBox &cUVArea, const Color &cColor=Color::white)
	Prepares the GPU to draw with this material.
virtual void	Deactivate (void)
	Sets the GPU back to its default state.
virtual float	Transparency (void) const
	Returns the overall transparency of the surface. Range 0..1. Not currently used.
virtual void	SetTransparency (float fTransparency)
	Sets the transparency of the surface.
virtual bool	TexturesVisible (void) const
	Returns true if textures should be visible on the rendered surface.
virtual void	SetTexturesVisible (bool bVisible)
	Sets if the textures should be visible on the surface.
virtual bool	IsTCNeeded (void) const
	Returns true if the material implementation needs texture coordinates from the mesh.
virtual bool	IsTNBNeeded (void) const
	Returns true if the material implementation needs tangent and binormal data from the mesh.
virtual unsigned int	TextureCount (void) const
	Returns the number of textures associated with the material.
virtual class TexturePool *	Texture (unsigned int iTextureIndex) const
	Returns a pointer to the specified texture. Do not delete this pointer.
virtual void	SetTextureTileLive (const AxisAlignedBoundingBox &cUVArea, bool bLive)
	Loads or unloads the specified uv tile for all textures in this material.
virtual bool	IsTextureTileLive (const AxisAlignedBoundingBox &cUVArea)
	Returns if the specified uv tile is loaded into memory.
virtual unsigned int	TextureTileCount () const
	Returns the number of texture tiles associated with this material.
virtual AxisAlignedBoundingBox	TextureTileArea (unsigned int iTileIndex) const
	Returns the uv area covered by the given tile.
virtual void	ActivateUVArea (const AxisAlignedBoundingBox &)
virtual VertexDataUsage	MapVertexData (VertexDataUsage eUsage) const
	This function is called to determine the mapping of vertex shader inputs for the material.
Static Public Member Functions
const mudbox::ClassDesc *	StaticClass (void)
mudbox::Node *	CreateInstances (unsigned int iCount=1)
Protected Member Functions
	Material (void)
	Constructor. Do not use it directly; Use CreateInstance() instead.

Member Enumeration Documentation

enum mudbox::Material::VertexDataUsage

This enum describes the usage of additional vertex data.

When a direct value is specified, the vertex data will be mapped to that channel. When a generic usage is specified, the current material object will be asked. See Material::MapVertexData and VertexDataProvider.

Enumeration values:

eVDUPosition	Position of the vertex in object space.
eVDUNormal	Normal of the vertex in object space.
eVDUTextureCoordinate	Texture coordinate.
eVDUVertexColor	Color of the vertex.
eVDUBoneIndices	Indices for the vertex in four dimension. TransformationPalette.
eVDUBoneWeights	Bone weights in three dimension. The weight of the last bone is calculated from the first three. TransformationPalette.
eVDUTangent	Tangent vector in object space.
eVDUBinormal	Binormal vector in object space.
eVDUDirectTextureCoordinate0	Indicatest the 0th texture coordinate channel.
eVDUDirectTextureCoordinate1	Indicatest the 1st texture coordinate channel.
eVDUDirectTextureCoordinate2	Indicatest the 2nd texture coordinate channel.
eVDUDirectTextureCoordinate3	Indicatest the 3rd texture coordinate channel.
eVDUDirectTextureCoordinate4	Indicatest the 4th texture coordinate channel.
eVDUDirectTextureCoordinate5	Indicatest the 5th texture coordinate channel.
eVDUDirectTextureCoordinate6	Indicatest the 6th texture coordinate channel.
eVDUDirectTextureCoordinate7	Indicatest the 7th texture coordinate channel.
eVDUNotUsed	Means that the data is not used by the material and can be skipped.

00071     {
00074         eVDUPosition, 
00075         eVDUNormal, 
00076         eVDUTextureCoordinate, 
00077         eVDUVertexColor, 
00078         eVDUBoneIndices, 
00079         eVDUBoneWeights, 
00080         eVDUTangent, 
00081         eVDUBinormal, 
00082 
00083 
00086         eVDUDirectTextureCoordinate0, 
00087         eVDUDirectTextureCoordinate1, 
00088         eVDUDirectTextureCoordinate2, 
00089         eVDUDirectTextureCoordinate3, 
00090         eVDUDirectTextureCoordinate4, 
00091         eVDUDirectTextureCoordinate5, 
00092         eVDUDirectTextureCoordinate6, 
00093         eVDUDirectTextureCoordinate7, 
00094 
00095 
00096         eVDUNotUsed 
00097     };

Constructor & Destructor Documentation

mudbox::Material::Material ( void ) [protected]

Constructor. Do not use it directly; Use CreateInstance() instead.

            Material *myMaterial = CreateInstance<Material>();

mudbox::Material::~Material

(

)

Member Function Documentation

virtual const mudbox::ClassDesc* mudbox::Material::RuntimeClass ( void ) const [inline, virtual]

Reimplemented from mudbox::TreeNode.

const mudbox::ClassDesc* mudbox::Material::StaticClass ( void ) [static]

Reimplemented from mudbox::TreeNode.

mudbox::Node* mudbox::Material::CreateInstances ( unsigned int iCount = 1 ) [static]

Reimplemented from mudbox::TreeNode.

virtual bool mudbox::Material::Activate	(	const Mesh *	pMesh,
		const AxisAlignedBoundingBox &	cUVArea,
		const Color &	cColor = `Color::white`
	)	`[virtual]`

Prepares the GPU to draw with this material.

This method is called by Mudbox when the material is about to used for a mesh. It should return true if additional rendering steps are needed. The cColor parameter is only as suggestion, its up to the material class how it uses (or ignores) it.

Parameters:

pMesh	[in] The mesh to be rendered
cUVArea	[in] The UV tile of the mesh to be rendered (each tile is drawn separately)
cColor	[in] The suggested color for the tile

virtual void mudbox::Material::Deactivate ( void ) [virtual]

Sets the GPU back to its default state.

virtual float mudbox::Material::Transparency ( void ) const [virtual]

Returns the overall transparency of the surface. Range 0..1. Not currently used.

It is up to the material implementation how it handles this overall transparency value. It can ignore it, but then the user wont be able to control the transparency of their objects in the scene. 0 means totally transparent while 1 means opaque. This is currently not used in mudbox (transparency is always 1) but it might be used in future versions.

virtual void mudbox::Material::SetTransparency ( float fTransparency ) [virtual]

Sets the transparency of the surface.

Range 0..1. Called by Mudbox when the user changes the transparency for an object. Not currently used.

Parameters:

fTransparency

[in] Ranges from 0 (transparent) to 1 (opaque)

virtual bool mudbox::Material::TexturesVisible ( void ) const [virtual]

Returns true if textures should be visible on the rendered surface.

It is up to the material implementation how it handles this parameter. It is provided in case a user wants to turn off texturing in the scene. In that case SetTexturesVisible() is called with false as the parameter.

If textures are set to invisible, then the material implementation should use a fixed value for the different channels that were using textures.

virtual void mudbox::Material::SetTexturesVisible ( bool bVisible ) [virtual]

Sets if the textures should be visible on the surface.

Parameters:

bVisible

[in] To make textures visible, set this to true.

virtual bool mudbox::Material::IsTCNeeded ( void ) const [virtual]

Returns true if the material implementation needs texture coordinates from the mesh.

If you are deriving a new material class, you need to have this method return true if your material needs texture coordinate information to draw itself properly.

virtual bool mudbox::Material::IsTNBNeeded ( void ) const [virtual]

Returns true if the material implementation needs tangent and binormal data from the mesh.

If you are deriving a new material class, you need to have this method return true if your material needs tangent and binormal data to draw itself properly.

virtual unsigned int mudbox::Material::TextureCount ( void ) const [virtual]

Returns the number of textures associated with the material.

virtual class TexturePool* mudbox::Material::Texture ( unsigned int iTextureIndex ) const [virtual]

Returns a pointer to the specified texture. Do not delete this pointer.

Parameters:

iTextureIndex

[in] Index of the texture to be returned

virtual void mudbox::Material::SetTextureTileLive	(	const AxisAlignedBoundingBox &	cUVArea,
		bool	bLive
	)	`[virtual]`

Loads or unloads the specified uv tile for all textures in this material.

To reduce memory footprint, users may opt to unload some tiles of the texture maps they are working with. This method is called by Mudbox to unload (remove from memory) or load (bring in from disk) those specific tiles. When a texture tile is unloaded, the material should use an arbitrary constant value for the channel it represents.

You probably don't need to override this method in your own materials.

Parameters:

cUVArea	[in] The UV bounds of the tile you want
bLive	[in] Specify true to load the tile, false to unload it.

virtual bool mudbox::Material::IsTextureTileLive ( const AxisAlignedBoundingBox & cUVArea ) [virtual]

Returns if the specified uv tile is loaded into memory.

Parameters:

cUVArea

[in] The UV bounds of the tile you are interested in

virtual unsigned int mudbox::Material::TextureTileCount ( ) const [virtual]

Returns the number of texture tiles associated with this material.

virtual AxisAlignedBoundingBox mudbox::Material::TextureTileArea ( unsigned int iTileIndex ) const [virtual]

Returns the uv area covered by the given tile.

Parameters:

iTileIndex

[in] The index of the tile of interest.

virtual void mudbox::Material::ActivateUVArea ( const AxisAlignedBoundingBox & ) [virtual]

virtual VertexDataUsage mudbox::Material::MapVertexData ( VertexDataUsage eUsage ) const [virtual]

This function is called to determine the mapping of vertex shader inputs for the material.

The return value must be a direct value. The value eNotUsed should be returned if the data is not used by the shader.

Parameters:

eUsage

[in] The usage to be mapped. This is always a generic value. See VertexDataUsage.

mudbox::Material Class Reference

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation